Skunkware 5

home *** CD-ROM | disk | FTP | other *** search

/ Skunkware 5 / Skunkware 5.iso / man / cat.3 / GetBitmap.3 < prev next >

Wrap

Text File | 1995-07-26 | 16.9 KB | 331 lines

TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp((((3333)))) TTTTkkkk (((( )))) TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp((((3333)))) _________________________________________________________________ NNNNAAAAMMMMEEEE Tk_GetBitmap, Tk_DefineBitmap, Tk_NameOfBitmap, Tk_SizeOfBitmap, Tk_FreeBitmap, Tk_GetBitmapFromData - maintain database of single-plane pixmaps SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS ####iiiinnnncccclllluuuuddddeeee <<<<ttttkkkk....hhhh>>>> Pixmap TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp((((_i_n_t_e_r_p, _t_k_w_i_n, _i_d)))) int | TTTTkkkk____DDDDeeeeffffiiiinnnneeeeBBBBiiiittttmmmmaaaapppp((((_i_n_t_e_r_p, _n_a_m_e_I_d, _s_o_u_r_c_e, _w_i_d_t_h, _h_e_i_g_h_t) | Tk_Uid TTTTkkkk____NNNNaaaammmmeeeeOOOOffffBBBBiiiittttmmmmaaaapppp((((_d_i_s_p_l_a_y, _b_i_t_m_a_p)))) | TTTTkkkk____SSSSiiiizzzzeeeeOOOOffffBBBBiiiittttmmmmaaaapppp((((_d_i_s_p_l_a_y, _b_i_t_m_a_p, _w_i_d_t_h_P_t_r, _h_e_i_g_h_t_P_t_r)))) | TTTTkkkk____FFFFrrrreeeeeeeeBBBBiiiittttmmmmaaaapppp((((_d_i_s_p_l_a_y, _b_i_t_m_a_p)))) | AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS Tcl_Interp *_i_n_t_e_r_p (in) Interpreter to use for error reporting. Tk_Window _t_k_w_i_n (in) Token for window in which the bitmap will be used. Tk_Uid _i_d (in) Description of bitmap; see below for possible values. Tk_Uid *_n_a_m_e_I_d (in) Name for new bitmap to be defined. char *_s_o_u_r_c_e (in) Data for bitmap, in standard bitmap format. Must be stored in static memory whose value will never change. unsigned int _w_i_d_t_h (in) Width of bitmap. unsigned int _h_e_i_g_h_t (in) Height of bitmap. unsigned int *_w_i_d_t_h_P_t_r (out) Pointer to word to fill in with _b_i_t_m_a_p's width. Page 1 (printed 7/23/95) TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp((((3333)))) TTTTkkkk (((( )))) TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp((((3333)))) unsigned int *_h_e_i_g_h_t_P_t_r (out) Pointer to word to fill in with _b_i_t_m_a_p's height. Display *_d_i_s_p_l_a_y (in) Display for which _b_i_t_m_a_p was allocated. | Pixmap _b_i_t_m_a_p (in) Identifier for a bitmap allocated by TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp. _________________________________________________________________ DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN These procedures manage a collection of bitmaps (one-plane pixmaps) being used by an application. The procedures allow bitmaps to be re-used efficiently, thereby avoiding server overhead, and also allow bitmaps to be named with character strings. TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp takes as argument a Tk_Uid describing a bitmap. It returns a Pixmap identifier for a bitmap corresponding to the description. It re-uses an existing bitmap, if possible, and creates a new one otherwise. At present, _i_d must have one of the following forms: @@@@_f_i_l_e_N_a_m_e _F_i_l_e_N_a_m_e must be the name of a file containing a bitmap description in the standard X11 or X10 format. _n_a_m_e _N_a_m_e must be the name of a bitmap defined previously with a call to TTTTkkkk____DDDDeeeeffffiiiinnnneeeeBBBBiiiittttmmmmaaaapppp. The following names are pre-defined by Tk: eeeerrrrrrrroooorrrr The international "don't" | symbol: a circle with a | diagonal line across it. ggggrrrraaaayyyy55550000 50% gray: a checkerboard pattern where every other bit is on. ggggrrrraaaayyyy22225555 25% gray: a pattern where 25% of the bits are on, consisting of all the bit positions that can be reached by a chess knight starting at (0,0). hhhhoooouuuurrrrggggllllaaaassssssss An hourglass symbol. | Page 2 (printed 7/23/95) TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp((((3333)))) TTTTkkkk (((( )))) TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp((((3333)))) iiiinnnnffffoooo || A large letter ``i''. | qqqquuuueeeesssstttthhhheeeeaaaadddd || The silhouette of a human | head, with a question mark | in it. | qqqquuuueeeessssttttiiiioooonnnn || A large question-mark. | wwwwaaaarrrrnnnniiiinnnngggg || A large exclamation point. Under normal conditions, TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp returns an identifier for the requested bitmap. If an error occurs in creating the bitmap, such as when _i_d refers to a non-existent file, then NNNNoooonnnneeee is returned and an error message is left in _i_n_t_e_r_p->_r_e_s_u_l_t. TTTTkkkk____DDDDeeeeffffiiiinnnneeeeBBBBiiiittttmmmmaaaapppp associates a name with in-memory bitmap data | so that the name can be used in later calls to TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp. | The _n_a_m_e_I_d argument gives a name for the bitmap; it must | not previously have been used in a call to TTTTkkkk____DDDDeeeeffffiiiinnnneeeeBBBBiiiittttmmmmaaaapppp. | The arguments _s_o_u_r_c_e, _w_i_d_t_h, and _h_e_i_g_h_t describe the bitmap. | TTTTkkkk____DDDDeeeeffffiiiinnnneeeeBBBBiiiittttmmmmaaaapppp normally returns TCL_OK; if an error occurs | (e.g. a bitmap named _n_a_m_e_I_d has already been defined) then | TCL_ERROR is returned and an error message is left in | _i_n_t_e_r_p->_r_e_s_u_l_t. Note: TTTTkkkk____DDDDeeeeffffiiiinnnneeeeBBBBiiiittttmmmmaaaapppp expects the memory | pointed to by _s_o_u_r_c_e to be static: TTTTkkkk____DDDDeeeeffffiiiinnnneeeeBBBBiiiittttmmmmaaaapppp doesn't | make a private copy of this memory, but uses the bytes | pointed to by _s_o_u_r_c_e later in calls to TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp. Typically TTTTkkkk____DDDDeeeeffffiiiinnnneeeeBBBBiiiittttmmmmaaaapppp is used by ####iiiinnnncccclllluuuuddddeeee-ing a bitmap file directly into a C program and then referencing the variables defined by the file. For example, suppose there exists a file ssssttttiiiipppp....bbbbiiiittttmmmmaaaapppp, which was created by the bbbbiiiittttmmmmaaaapppp program and contains a stipple pattern. The following code uses TTTTkkkk____DDDDeeeeffffiiiinnnneeeeBBBBiiiittttmmmmaaaapppp to define a new bitmap named ffffoooooooo: Pixmap bitmap; #include "stip.bitmap" Tk_DefineBitmap(interp, Tk_GetUid("foo"), stip_bits, stip_width, stip_height); ... bitmap = Tk_GetBitmap(interp, tkwin, Tk_GetUid("foo")); This code causes the bitmap file to be read at compile-time and incorporates the bitmap information into the program's executable image. The same bitmap file could be read at run-time using TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp: Pixmap bitmap; bitmap = Tk_GetBitmap(interp, tkwin, Tk_GetUid("@stip.bitmap")); Page 3 (printed 7/23/95) TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp((((3333)))) TTTTkkkk (((( )))) TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp((((3333)))) The second form is a bit more flexible (the file could be modified after the program has been compiled, or a different string could be provided to read a different file), but it is a little slower and requires the bitmap file to exist separately from the program. TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp maintains a database of all the bitmaps that have been created. Whenever possible, it will return an existing bitmap rather than creating a new one. This approach can substantially reduce server overhead, so TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp should generally be used in preference to Xlib procedures like XXXXRRRReeeeaaaaddddBBBBiiiittttmmmmaaaappppFFFFiiiilllleeee. The bitmaps returned by TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp are shared, so callers should never modify them. If a bitmap must be modified dynamically, then it should be created by calling Xlib procedures such as XXXXRRRReeeeaaaaddddBBBBiiiittttmmmmaaaappppFFFFiiiilllleeee or XXXXCCCCrrrreeeeaaaatttteeeePPPPiiiixxxxmmmmaaaapppp directly. The procedure TTTTkkkk____NNNNaaaammmmeeeeOOOOffffBBBBiiiittttmmmmaaaapppp is roughly the inverse of TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp. Given an X Pixmap argument, it returns the _i_d that was passed to TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp when the bitmap was created. | _B_i_t_m_a_p must have been the return value from a previous call | to TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp. TTTTkkkk____SSSSiiiizzzzeeeeOOOOffffBBBBiiiittttmmmmaaaapppp returns the dimensions of its _b_i_t_m_a_p | argument in the words pointed to by the _w_i_d_t_h_P_t_r and | _h_e_i_g_h_t_P_t_r arguments. As with TTTTkkkk____NNNNaaaammmmeeeeOOOOffffBBBBiiiittttmmmmaaaapppp, _b_i_t_m_a_p must | have been created by TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp. When a bitmap returned by TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp is no longer needed, TTTTkkkk____FFFFrrrreeeeeeeeBBBBiiiittttmmmmaaaapppp should be called to release it. There should be exactly one call to TTTTkkkk____FFFFrrrreeeeeeeeBBBBiiiittttmmmmaaaapppp for each call to TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp. When a bitmap is no longer in use anywhere (i.e. it has been freed as many times as it has been gotten) TTTTkkkk____FFFFrrrreeeeeeeeBBBBiiiittttmmmmaaaapppp will release it to the X server and delete it from the database. BBBBUUUUGGGGSSSS In determining whether an existing bitmap can be used to satisfy a new request, TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp considers only the immediate value of its _i_d argument. For example, when a file name is passed to TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp, TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp will assume it is safe to re-use an existing bitmap created from the same file name: it will not check to see whether the file itself has changed, or whether the current directory has changed, thereby causing the name to refer to a different file. KKKKEEEEYYYYWWWWOOOORRRRDDDDSSSS PPPPaaaaggggeeee 4444 ((((pppprrrriiiinnnntttteeeedddd 7777////22223333////99995555)))) TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp((((3333)))) TTTTkkkk (((( )))) TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp((((3333)))) bitmap, pixmap Page 5 (printed 7/23/95)